iT邦幫忙

4

.NET Framework4.7.2 製作 Web API 使用 [NSwag] 套件呈現 Swagger UI + JWT Authentication 及跨域處理(CORS)

swagger jwt .net web api cors
龜人 2022-03-05 20:47:27 ‧ 8996 瀏覽

  • 分享至 

  • xImage
    •  

本文將介紹如何使用 JWT 保持登入狀態，配合 Swagger / OpenAPI 呈現。

.NET Framework 4.7.2

開發環境

  • Visual Studio 2019
  • AspNet.Mvc version="5.2.7"
  • AspNet.WebApi version="5.2.7"
  • EntityFramework version="6.1.3"

Web API 使用 JWT Authentication 進行資料驗證

參考資料

NuGet 安裝套件

  • jose-jwt version="3.2.0"

程式碼實作

  1. 建立一個類別 JwtAuthUtil.cs，負責 token 生成相關功能

    using Jose;
using System;
using System.Collections.Generic;
using System.Text;
using System.Web.Configuration;
using MyWebApiProject.Models;

namespace MyWebApiProject.Security
{
	/// <summary>
    /// JwtToken 生成功能
    /// </summary>
    public class JwtAuthUtil
    {
        private readonly ApplicationDbContext db = new ApplicationDbContext(); // DB 連線

        /// <summary>
        /// 生成 JwtToken
        /// </summary>
        /// <param name="id">會員id</param>
        /// <returns>JwtToken</returns>
        public string GenerateToken(int id)
        {
			// 自訂字串，驗證用，用來加密送出的 key (放在 Web.config 的 appSettings)
            string secretKey = WebConfigurationManager.AppSettings["TokenKey"]; // 從 appSettings 取出
            var user = db.User.Find(id); // 進 DB 取出想要夾帶的基本資料

			// payload 需透過 token 傳遞的資料 (可夾帶常用且不重要的資料)
            var payload = new Dictionary<string, object>
            {
                { "Id", user.Id },
                { "Account", user.Account },
                { "NickName", user.NickName },
                { "Image", user.Image },
                { "Exp", DateTime.Now.AddMinutes(30).ToString() } // JwtToken 時效設定 30 分
            };

			// 產生 JwtToken
            var token = JWT.Encode(payload, Encoding.UTF8.GetBytes(secretKey), JwsAlgorithm.HS512);
            return token;
        }

        /// <summary>
        /// 生成只刷新效期的 JwtToken
        /// </summary>
        /// <returns>JwtToken</returns>
        public string ExpRefreshToken(Dictionary<string, object> tokenData)
        {
            string secretKey = WebConfigurationManager.AppSettings["TokenKey"];
			// payload 從原本 token 傳遞的資料沿用，並刷新效期
            var payload = new Dictionary<string, object>
            {
                { "Id", (int)tokenData["Id"] },
                { "Account", tokenData["Account"].ToString() },
                { "NickName", tokenData["NickName"].ToString() },
                { "Image", tokenData["Image"].ToString() },
                { "Exp", DateTime.Now.AddMinutes(30).ToString() } // JwtToken 時效刷新設定 30 分
            };

			//產生刷新時效的 JwtToken
            var token = JWT.Encode(payload, Encoding.UTF8.GetBytes(secretKey), JwsAlgorithm.HS512);
            return token;
        }

        /// <summary>
        /// 生成無效 JwtToken
        /// </summary>
        /// <returns>JwtToken</returns>
        public string RevokeToken()
        {
            string secretKey = "RevokeToken"; // 故意用不同的 key 生成
            var payload = new Dictionary<string, object>
            {
                { "Id", 0 },
                { "Account", "None" },
                { "NickName", "None" },
                { "Image", "None" },
                { "Exp", DateTime.Now.AddDays(-15).ToString() } // 使 JwtToken 過期 失效
            };

			// 產生失效的 JwtToken
            var token = JWT.Encode(payload, Encoding.UTF8.GetBytes(secretKey), JwsAlgorithm.HS512);
            return token;
        }
    }
}

  2. 在登入功能的 API 確認登入成功後，生成 JwtToken 並回傳給前端

    // GenerateToken() 生成新 JwtToken 用法
JwtAuthUtil jwtAuthUtil = new JwtAuthUtil();
string jwtToken = jwtAuthUtil.GenerateToken(userQuery.Id); 
// 登入成功時，回傳登入成功順便夾帶 JwtToken
return Ok(new { Status = true, JwtToken = jwtToken });

  3. 前端將收到的 JWT-Token 字串存入瀏覽器 localStorage

    https://ithelp.ithome.com.tw/upload/images/20220306/201394877aehPsLye1.jpg

  4. 建立一個類別 JwtAuthFilter.cs，負責生成 [JwtAuthFilter] 標籤，可放於需登入的 API 上，用來檢核 JWT-Token 是否正確

    using Jose;
using Newtonsoft.Json;
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Text;
using System.Web.Configuration;
using System.Web.Http;
using System.Web.Http.Controllers;
using System.Web.Http.Filters;

namespace MyWebApiProject.Security
{
    /// <summary>
    /// JwtAuthFilter 繼承 ActionFilterAttribute 可生成 [JwtAuthFilter] 使用
    /// </summary>
    public class JwtAuthFilter : ActionFilterAttribute
    {
        // 加解密的 key，如果不一樣會無法成功解密
        private static readonly string secretKey = WebConfigurationManager.AppSettings["TokenKey"];

        /// <summary>
        /// 過濾有用標籤 [JwtAuthFilter] 請求的 API 的 JwtToken 狀態及內容
        /// </summary>
        /// <param name="actionContext"></param>
        public override void OnActionExecuting(HttpActionContext actionContext)
        {
            // 取出請求內容並排除不需要驗證的 API
            var request = actionContext.Request;
            if (!WithoutVerifyToken(request.RequestUri.ToString())) {
                // 有取到 JwtToken 後，判斷授權格式不存在且不正確時
                if (request.Headers.Authorization == null || request.Headers.Authorization.Scheme != "Bearer") {
                    // 可考慮配合前端專案開發期限，不修改 StatusCode 預設 200，將請求失敗搭配 Status: false 供前端判斷
                    string messageJson = JsonConvert.SerializeObject(new { Status = false, Message = "請重新登入" }); // JwtToken 遺失，需導引重新登入
                    var errorMessage = new HttpResponseMessage()
                    {
                        // StatusCode = System.Net.HttpStatusCode.Unauthorized, // 401
                        ReasonPhrase = "JwtToken Lost",
                        Content = new StringContent(messageJson,
                                    Encoding.UTF8,
                                    "application/json")
                    };
                    throw new HttpResponseException(errorMessage); // Debug 模式會停在此行，點繼續執行即可
                }
                else {
                    try {
                        // 有 JwtToken 且授權格式正確時執行，用 try 包住，因為如果有篡改可能解密失敗
                        // 解密後會回傳 Json 格式的物件 (即加密前的資料)
                        var jwtObject = GetToken(request.Headers.Authorization.Parameter);

                        // 檢查有效期限是否過期，如 JwtToken 過期，需導引重新登入
                        if (IsTokenExpired(jwtObject["Exp"].ToString())) {
                            string messageJson = JsonConvert.SerializeObject(new { Status = false, Message = "請重新登入" }); // JwtToken 過期，需導引重新登入
                            var errorMessage = new HttpResponseMessage()
                            {
                                // StatusCode = System.Net.HttpStatusCode.Unauthorized, // 401
                                ReasonPhrase = "JwtToken Expired",
                                Content = new StringContent(messageJson,
                                    Encoding.UTF8,
                                    "application/json")
                            };
                            throw new HttpResponseException(errorMessage); // Debug 模式會停在此行，點繼續執行即可
                        }
                    }
                    catch (Exception) {
                        // 解密失敗
                        string messageJson = JsonConvert.SerializeObject(new { Status = false, Message = "請重新登入" }); // JwtToken 不符，需導引重新登入
                        var errorMessage = new HttpResponseMessage()
                        {
                            // StatusCode = System.Net.HttpStatusCode.Unauthorized, // 401
                            ReasonPhrase = "JwtToken NotMatch",
                            Content = new StringContent(messageJson,
                                    Encoding.UTF8,
                                    "application/json")
                        };
                        throw new HttpResponseException(errorMessage); // Debug 模式會停在此行，點繼續執行即可
                    }
                }
            }
            base.OnActionExecuting(actionContext);
        }

        /// <summary>
        /// 將 Token 解密取得夾帶的資料
        /// </summary>
        /// <param name="token"></param>
        /// <returns></returns>
        public static Dictionary<string, object> GetToken(string token)
        {
            return JWT.Decode<Dictionary<string, object>>(token, Encoding.UTF8.GetBytes(secretKey), JwsAlgorithm.HS512);
        }

        /// <summary>
        /// 有在 Global 設定一律檢查 JwtToken 時才需設定排除，例如 Login 不需要驗證因為還沒有 token
        /// </summary>
        /// <param name="requestUri"></param>
        /// <returns></returns>
        public bool WithoutVerifyToken(string requestUri)
        {
            //if (requestUri.EndsWith("/login")) return true;
            return false;
        }

        /// <summary>
        /// 驗證 token 時效
        /// </summary>
        /// <param name="dateTime"></param>
        /// <returns></returns>
        public bool IsTokenExpired(string dateTime)
        {
            return Convert.ToDateTime(dateTime) < DateTime.Now;
        }
    }
}

  5. 使用者用到需登入的 API 時，前端取出瀏覽器 localStorage 中的 JWT-Token 字串用於請求的 Header 裡 Authorization 欄位用 Bearer 規則夾帶

  6. 將 [JwtAuthFilter] 標籤，放於需登入的 API 上，檢核 JWT-Token 是否正確，並刷新效期

    // 取出請求內容，解密 JwtToken 取出資料
var userToken = JwtAuthFilter.GetToken(Request.Headers.Authorization.Parameter);
// ExpRefreshToken() 生成刷新效期 JwtToken 用法
JwtAuthUtil jwtAuthUtil = new JwtAuthUtil();
string jwtToken = jwtAuthUtil.ExpRefreshToken(userToken);
// Do Something ~
// 處理完請求內容後，順便送出刷新效期的 JwtToken
return Ok(new { Status = true, JwtToken = jwtToken });

  7. 用於強制登出使用者的方式

    // RevokeToken() 生成失效的 JwtToken 用法
JwtAuthUtil jwtAuthUtil = new JwtAuthUtil();
string jwtToken = jwtAuthUtil.RevokeToken();
// 用於登出使用者時，刷新為失效的 JwtToken
return Ok(new { Status = true, jwtToken = jwtToken });

Web API 使用 [NSwag] 套件呈現 Swagger UI

參考資料

NuGet 安裝套件

  • NSwag.AspNet.Owin version="13.15.9"
  • NSwag.Annotations version="13.2.5"
  • Microsoft.AspNet.WebApi.Owin version="5.2.7"
  • Microsoft.Owin.Host.SystemWeb version="4.2.0"

程式碼實作

  1. 在專案新增 OWIN 啟動類別 Startup.cs，並加入相關設定

    https://ithelp.ithome.com.tw/upload/images/20220305/201394870JiGbKTEHL.jpg

    using Microsoft.Owin;
using NSwag;
using NSwag.AspNet.Owin;
using NSwag.Generation.Processors.Security;
using Owin;
using System.Web.Http;

[assembly: OwinStartup(typeof(MyWebApiProject.Startup))]

namespace MyWebApiProject
{
    /// <summary>
    /// OWIN 啟動類別
    /// </summary>
    public class Startup
    {
        /// <summary>
        /// 應用程式配置
        /// </summary>
        /// <param name="app"></param>
        public void Configuration(IAppBuilder app)
        {
            // 如需如何設定應用程式的詳細資訊，請瀏覽 https://go.microsoft.com/fwlink/?LinkID=316888
            var config = new HttpConfiguration();

            // 針對 JSON 資料使用 camel (JSON 回應會改 camel，但 Swagger 提示不會)
            //config.Formatters.JsonFormatter.SerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();

            app.UseSwaggerUi3(typeof(Startup).Assembly, settings =>
            {
                // 針對 WebAPI，指定路由包含 Action 名稱
                settings.GeneratorSettings.DefaultUrlTemplate =
                    "api/{controller}/{action}/{id?}";
                // 加入客製化調整邏輯名稱版本等
                settings.PostProcess = document =>
                {
                    document.Info.Title = "WebAPI : 專案名稱";
                };
                // 加入 Authorization JWT token 定義
                settings.GeneratorSettings.DocumentProcessors.Add(new SecurityDefinitionAppender("Bearer", new OpenApiSecurityScheme()
                {
                    Type = OpenApiSecuritySchemeType.ApiKey,
                    Name = "Authorization",
                    Description = "Type into the textbox: Bearer {your JWT token}.",
                    In = OpenApiSecurityApiKeyLocation.Header,
                    Scheme = "Bearer" // 不填寫會影響 Filter 判斷錯誤
                }));
                // REF: https://github.com/RicoSuter/NSwag/issues/1304 (每支 API 單獨呈現認證 UI 圖示)
                settings.GeneratorSettings.OperationProcessors.Add(new OperationSecurityScopeProcessor("Bearer"));
            });
            app.UseWebApi(config);
            config.MapHttpAttributeRoutes();
            config.EnsureInitialized();
        }
    }
}

  2. 於專案屬性的建置內容勾選輸出 XML 文件檔案， Swagger UI 才會有方法及參數說明

    https://ithelp.ithome.com.tw/upload/images/20220305/20139487ECH4vCNbkV.jpg

  3. 於 Web.config 加入處理器設定，將 URL /swagger/* 導向 NSwag 處理程式

    <configuration>
	<system.webServer>
		<handlers>
			<add name="NSwag" path="swagger" verb="*" type="System.Web.Handlers.TransferRequestHandler" preCondition="integratedMode,runtimeVersionv4.0" />
		</handlers>
	</system.webServer>
</configuration>

  4. 於 API 及輸入欄位加上 /// 撰寫 XML 方法及參數說明

  5. 使用登入 API 取得回傳的 JWT token 於 Swagger UI 的 Authorization JWT token 輸入驗證時，使用 Bearer + 空格 + JWT token 夾帶

    https://ithelp.ithome.com.tw/upload/images/20220305/20139487ge4lNo0f8V.jpg

  6. 可於 ApiController 上加入 [OpenApiTag] 描述整個模組功能

    [OpenApiTag("Users", Description = "使用者操作功能")]
public class UsersController : ApiController
{
	/// <summary>
    /// 1-5 聯絡我們功能 (JWT)
    /// </summary>
    /// <param name="contactUsVm">留言資料</param>
    /// <returns></returns>
	/// <summary>
    [JwtAuthFilter] // 用於檢核 JWT-Token 
    [HttpPost]
    [SwaggerResponse(typeof(ApiResult))] // 顯示回傳資料的註解
    [Route("api/users/contact-us")]
    public IHttpActionResult SendContactUsMail(ContactUsVm contactUsVm)
    {
        // Do Sometning

        // 取出請求內容，解密 JwtToken 取出資料
        var userToken = JwtAuthFilter.GetToken(Request.Headers.Authorization.Parameter);
        //單純刷新效期不新生成，新生成會進資料庫
        JwtAuthUtil jwtAuthUtil = new JwtAuthUtil();
        string jwtToken = jwtAuthUtil.ExpRefreshToken(userToken);
        // 送出刷新 JwtToken
        return Ok(new ApiResult { Status = true, JwtToken = jwtToken });
	}
}

    https://ithelp.ithome.com.tw/upload/images/20220310/20139487DbSPitvvSq.jpg

跨域處理(CORS)

由於使用 OWIN 啟動會改成由 Startup.cs 類別管理，因此需將放行的請求類型及跨域操作加入。

參考資料

NuGet 安裝套件

  • Microsoft.Owin.Cors version="4.2.0"
  • Microsoft.Owin.Security.OAuth version="4.2.0"

程式碼實作

  1. 刪除原 Web API 2 官方建議的作法，於 NuGet 移除 Microsoft.AspNet.WebApi.Cors

  2. 於 Startup.cs 設定最上方加入啟用跨域及驗證

    using Microsoft.Owin;
using Microsoft.Owin.Security.OAuth;
using NSwag;
using NSwag.AspNet.Owin;
using NSwag.Generation.Processors.Security;
using Owin;
using System.Web.Http;
using Thak_tshehWebAPI.Security;

[assembly: OwinStartup(typeof(MyWebApiProject.Startup))]

namespace MyWebApiProject
{
    /// <summary>
    /// OWIN 啟動類別
    /// </summary>
    public class Startup
    {
        /// <summary>
        /// 應用程式配置
        /// </summary>
        /// <param name="app"></param>
        public void Configuration(IAppBuilder app)
        {
            // 啟用跨域及驗證配置
            ConfigureAuth(app);

            var config = new HttpConfiguration();

            // 針對 JSON 資料使用 camel (JSON 回應會改 camel，但 Swagger 提示不會)
            //config.Formatters.JsonFormatter.SerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();

            app.UseSwaggerUi3(typeof(Startup).Assembly, settings =>
            {
                // 針對 WebAPI，指定路由包含 Action 名稱
                settings.GeneratorSettings.DefaultUrlTemplate =
                    "api/{controller}/{action}/{id?}";
                // 加入客製化調整邏輯名稱版本等
                settings.PostProcess = document =>
                {
                    document.Info.Title = "WebAPI : 專案名稱";
                };
                // 加入 Authorization JWT token 定義
                settings.GeneratorSettings.DocumentProcessors.Add(new SecurityDefinitionAppender("Bearer", new OpenApiSecurityScheme()
                {
                    Type = OpenApiSecuritySchemeType.ApiKey,
                    Name = "Authorization",
                    Description = "Type into the textbox: Bearer {your JWT token}.",
                    In = OpenApiSecurityApiKeyLocation.Header,
                    Scheme = "Bearer" // 不填寫會影響 Filter 判斷錯誤
                }));
                // REF: https://github.com/RicoSuter/NSwag/issues/1304 (每支 API 單獨呈現認證 UI 圖示)
                settings.GeneratorSettings.OperationProcessors.Add(new OperationSecurityScopeProcessor("Bearer"));
            });
            app.UseWebApi(config);
            config.MapHttpAttributeRoutes();
            config.EnsureInitialized();
        }

        /// <summary>
        /// 啟用跨域及驗證配置
        /// </summary>
        /// <param name="app"></param>
        private void ConfigureAuth(IAppBuilder app)
        {
            // 建立 OAuth 配置
            var oAuthOptions = new OAuthAuthorizationServerOptions
            {
                Provider = new AuthorizationServerProvider()
            };

            // 啟用 OAuth2 bearer tokens 驗證並加入配置
            app.UseOAuthAuthorizationServer(oAuthOptions);
        }
    }
}

  3. 新增 AuthorizationServerProvider.cs 類別檔，設定跨域 Request Headers 處理邏輯

    using Microsoft.Owin;
using Microsoft.Owin.Security.OAuth;
using System;
using System.Configuration;
using System.Linq;
using System.Threading.Tasks;

namespace MyWebApiProject.Security
{
    /// <summary>
    /// OAuth 配置並繼承 OAuthAuthorizationServerProvider
    /// </summary>
    public class AuthorizationServerProvider : OAuthAuthorizationServerProvider
    {
        /// <summary>
        /// 在驗證客戶端身分前調用，並依客戶端請求來源配置 CORS 允許類型設定
        /// </summary>
        /// <param name="context"></param>
        /// <returns></returns>
        public override Task MatchEndpoint(OAuthMatchEndpointContext context)
        {
            // 依請求來源配置 CORS 允許類型設定
            SetCORSPolicy(context.OwinContext);

            // 如果請求為預檢請求則設為完成直接回傳
            if (context.Request.Method == "OPTIONS") {
                context.RequestCompleted();
                return Task.FromResult(0);
            }

            return base.MatchEndpoint(context);
        }

        /// <summary>
        /// 依請求來源配置 CORS 允許類型設定
        /// </summary>
        /// <param name="context"></param>
        private void SetCORSPolicy(IOwinContext context)
        {
            // 取出允許跨域的網址 (放在 Web.config 的 appSettings)
            string allowedUrls = ConfigurationManager.AppSettings["allowedOrigins"];

            // 有填寫允許跨域的網址，就分割取出判斷請求的來源是否等於允許跨域的網址，並將允許網址加入 Headers
            if (!String.IsNullOrWhiteSpace(allowedUrls)) {
                var list = allowedUrls.Split(',');
                if (list.Length > 0) {
                    string origin = context.Request.Headers.Get("Origin");
                    var found = list.Where(item => item == origin).Any();
                    if (found) {
                        context.Response.Headers.Add("Access-Control-Allow-Origin",
                                                     new string[] { origin });
                    }
                }
            }
            // 配置允許請求的 Headers 內容
            context.Response.Headers.Add("Access-Control-Allow-Headers",
                                   new string[] { "Authorization", "Content-Type" });
            // 配置允許請求的 Headers 方法
            context.Response.Headers.Add("Access-Control-Allow-Methods",
                                   new string[] { "OPTIONS", "GET", "POST", "PUT", "DELETE"});
        }
    }
}

  4. 於 Web.config 加入允許前端跨域請求的網址 (若無需求可不填)

    • 可填測試網域或前端開發時使用的本地端網域，用逗點區隔添加
    <configuration>
  <appSettings>
	  <!--Owin CORS-->
	  <add key="allowedOrigins" value="https://www.myfriendproject.com,https://localhost:44444,http://127.0.0.1:5500" />
  </appSettings>
</configuration>

注意事項

  • 複雜型別 ⇒ 會自動轉到 Body ⇒ 所以如果要當 GET 用並夾在 uri ⇒ API輸入資料型別前才要加 [FromUri] ⇒ Swagger UI 會變成每個值都是個別輸入欄位
  • 簡單型別 ⇒ 會自動轉到 Uri ⇒ 所以如果要當 POST 用並藏到 body ⇒ API輸入資料型別前才要加 [FromBody] ⇒ Swagger UI 會變成一個可以輸入多行的欄位 
[OpenApiTag("Users", Description = "使用者操作功能")]
public class UsersController : ApiController
{
    /// <summary>
    /// 1-5 聯絡我們功能 (JWT)
    /// </summary>
    /// <param name="contactUsVm">留言資料</param>
    /// <returns></returns>
    /// <summary>
    [JwtAuthFilter] // 用於檢核 JWT-Token 
    [HttpPost]
    [SwaggerResponse(typeof(ApiResult))] // 顯示回傳資料的註解
    [Route("api/users/contact-us")]
    public IHttpActionResult SendContactUsMail([FromUri] ContactUsVm contactUsVm)
    {
        // Do Sometning
    }
}

https://ithelp.ithome.com.tw/upload/images/20220310/20139487RgGjPa5auE.jpg


圖片
  直播研討會
圖片
{{ item.channelVendor }} {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

尚未有邦友留言

立即登入留言
iThome鐵人賽
參賽組數
1064 組
團體組數
40 組
累計文章數
22200 篇
完賽人數
602 人
iT+看影片追技術 看影片追技術 看更多
熱門tag 看更多
15th鐵人賽 16th鐵人賽 13th鐵人賽 14th鐵人賽 12th鐵人賽 11th鐵人賽 鐵人賽 2019鐵人賽 javascript 2018鐵人賽 python 2017鐵人賽 windows php c# windows server linux css react vue.js
熱門問題
熱門回答
熱門文章
IT邦幫忙